/**
 * ============用户认证路由配置开始===========
 * 用户认证路由配置 - 定义所有用户认证相关的API端点
 * User Authentication Routes Configuration - Defines all user authentication related API endpoints
 * 
 * 功能说明：
 * - 提供用户注册、登录、验证码发送等公开API端点
 * - 提供用户信息管理、密码修改等需要认证的API端点
 * - 使用Express Router模块化管理路由
 * - 集成认证中间件保护敏感操作
 * 
 * 路由分类：
 * 1. 公开路由：无需认证即可访问，如注册、登录、验证码发送
 * 2. 受保护路由：需要JWT令牌认证，如用户信息获取和修改
 * 
 * 依赖模块说明：
 * - express: Web框架，提供路由功能
 * - authController: 认证控制器，包含所有业务逻辑处理函数
 * - authMiddleware: 认证中间件，验证JWT令牌有效性
 */

// 导入 Express 路由模块 - Import Express router module
import express from "express";

// 导入认证控制器中的所有处理函数 - Import all handler functions from auth controller
import {
  requestSmsCode,    // 发送短信验证码处理函数 - SMS code request handler
  requestEmailCode,  // 发送邮箱验证码处理函数 - Email code request handler
  register,          // 用户注册处理函数 - User registration handler
  login,             // 用户登录处理函数 - User login handler
} from "../controllers/authController.js";

// 导入认证中间件 - Import authentication middleware
import authMiddleware from "../middleware/auth.js";

/**
 * ============路由实例创建开始===========
 * 创建Express路由实例
 * Create Express router instance
 * 
 * 功能说明：
 * - express.Router() 创建模块化的路由处理程序
 * - 可以像中间件一样挂载到应用程序上
 * - 支持路由级别的中间件和参数处理
 * 
 * 使用方式：
 * - 在主应用中通过 app.use('/api/auth', authRoutes) 挂载
 * - 所有路由都会自动添加 /api/auth 前缀
 */
const router = express.Router();

/**
 * ============公开路由（无需认证）开始===========
 * Public routes (no authentication required)
 * 
 * 这些路由不需要用户登录即可访问，主要用于：
 * - 用户注册和登录流程
 * - 验证码发送功能
 * - 第三方登录集成
 * 
 * 安全考虑：
 * - 虽然是公开路由，但仍需要进行参数验证
 * - 实施频率限制防止恶意请求
 * - 验证码发送需要防止短信轰炸
 */

/**
 * POST /api/auth/sms-code - 发送短信验证码
 * Send SMS verification code
 * 
 * @route POST /api/auth/sms-code
 * @access Public - 公开访问，无需认证
 * @param {string} phone - 手机号码（请求体中）
 * @returns {Object} 响应对象包含成功状态和提示信息
 * @throws {400} 手机号格式错误
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 向指定手机号发送6位数字验证码
 * - 验证码有效期5分钟
 * - 支持注册和登录场景使用
 * - 开发环境下返回验证码便于测试
 * 
 * 请求示例：
 * POST /api/auth/sms-code
 * Content-Type: application/json
 * {
 *   "phone": "13800138000"
 * }
 * 
 * 响应示例：
 * {
 *   "success": true,
 *   "message": "验证码已发送",
 *   "data": {
 *     "phone": "13800138000",
 *     "code": "123456"  // 仅开发环境
 *   }
 * }
 */
router.post("/sms-code", requestSmsCode);

/**
 * POST /api/auth/email-code - 发送邮箱验证码
 * Send email verification code
 * 
 * @route POST /api/auth/email-code
 * @access Public - 公开访问，无需认证
 * @param {string} email - 邮箱地址（请求体中）
 * @returns {Object} 响应对象包含成功状态和提示信息
 * @throws {400} 邮箱格式错误
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 向指定邮箱发送6位数字验证码
 * - 验证码有效期10分钟（比短信稍长）
 * - 支持注册和登录场景使用
 * - 开发环境下返回验证码便于测试
 * 
 * 请求示例：
 * POST /api/auth/email-code
 * Content-Type: application/json
 * {
 *   "email": "user@example.com"
 * }
 * 
 * 响应示例：
 * {
 *   "success": true,
 *   "message": "验证码已发送",
 *   "data": {
 *     "email": "user@example.com",
 *     "code": "123456"  // 仅开发环境
 *   }
 * }
 */
router.post("/email-code", requestEmailCode);

/**
 * POST /api/auth/register - 用户注册
 * User registration
 * 
 * @route POST /api/auth/register
 * @access Public - 公开访问，无需认证
 * @param {string} password - 用户密码，至少6位字符
 * @param {string} [phone] - 手机号（手机注册时必填）
 * @param {string} [smsCode] - 短信验证码（手机注册时必填）
 * @param {string} [email] - 邮箱地址（邮箱注册时必填）
 * @param {string} [emailCode] - 邮箱验证码（邮箱注册时必填）
 * @returns {Object} 响应对象包含用户信息和JWT令牌
 * @throws {400} 参数验证失败或验证码无效
 * @throws {409} 账户已存在
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 支持手机号和邮箱两种注册方式
 * - 验证码验证通过后创建新用户
 * - 密码使用bcrypt加密存储
 * - 注册成功自动生成JWT令牌
 * - 防止重复注册
 * 
 * 请求示例（手机注册）：
 * POST /api/auth/register
 * Content-Type: application/json
 * {
 *   "phone": "13800138000",
 *   "smsCode": "123456",
 *   "password": "password123"
 * }
 * 
 * 请求示例（邮箱注册）：
 * POST /api/auth/register
 * Content-Type: application/json
 * {
 *   "email": "user@example.com",
 *   "emailCode": "123456",
 *   "password": "password123"
 * }
 * 
 * 响应示例：
 * {
 *   "success": true,
 *   "message": "注册成功",
 *   "data": {
 *     "user": {
 *       "id": 1,
 *       "phone": "13800138000",
 *       "loginProvider": "phone"
 *     },
 *     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 *   }
 * }
 */
router.post("/register", register);

/**
 * POST /api/auth/login - 用户登录
 * User login
 * 
 * @route POST /api/auth/login
 * @access Public - 公开访问，无需认证
 * @param {string} account - 账户（手机号或邮箱）
 * @param {string} password - 用户密码
 * @param {string} loginType - 登录类型（"phone" 或 "email"）
 * @returns {Object} 响应对象包含用户信息和JWT令牌
 * @throws {400} 参数验证失败或格式错误
 * @throws {404} 账户不存在
 * @throws {401} 密码错误
 * @throws {500} 服务器内部错误
 * 
 * 功能说明：
 * - 支持手机号和邮箱两种登录方式
 * - 使用bcrypt验证密码安全性
 * - 登录成功生成JWT令牌
 * - 返回用户基本信息（不含敏感数据）
 * 
 * 请求示例（手机登录）：
 * POST /api/auth/login
 * Content-Type: application/json
 * {
 *   "account": "13800138000",
 *   "password": "password123",
 *   "loginType": "phone"
 * }
 * 
 * 请求示例（邮箱登录）：
 * POST /api/auth/login
 * Content-Type: application/json
 * {
 *   "account": "user@example.com",
 *   "password": "password123",
 *   "loginType": "email"
 * }
 * 
 * 响应示例：
 * {
 *   "success": true,
 *   "message": "登录成功",
 *   "data": {
 *     "user": {
 *       "id": 1,
 *       "phone": "13800138000",
 *       "email": null,
 *       "loginProvider": "phone"
 *     },
 *     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 *   }
 * }
 */
router.post("/login", login);

/**
 * ============公开路由结束===========
 * End of public routes
 * 
 * 注意事项：
 * - 公开路由虽然无需认证，但仍需要进行严格的参数验证
 * - 建议在生产环境中对这些路由实施频率限制
 * - 验证码相关路由需要防止恶意刷取验证码
 */

/**
 * ============路由导出开始===========
 * 导出路由配置供应用使用
 * Export router configuration for app use
 * 
 * 使用说明：
 * - 在主应用文件（如app.js）中导入此路由配置
 * - 通过 app.use('/api/auth', authRoutes) 挂载到应用
 * - 所有路由将自动获得 /api/auth 前缀
 * 
 * 示例：
 * import authRoutes from './routes/authRoutes.js';
 * app.use('/api/auth', authRoutes);
 */
export default router;
// ============用户认证路由配置结束===========
